1 Tag object

In this basic tutorial, we run through all the steps of GeoPressureR using only pressure data, with the simple example of a Swainson’s Warbler. This bird presents a short migration route, with only a few stopovers, making it fast to compute.

Swainson’s Warbler. 16 May 2022. Edisto Nature Trail, South Carolina, US. ML 450511161
Swainson’s Warbler. 16 May 2022. Edisto Nature Trail, South Carolina, US. ML 450511161

1.1 Create tag

The tag object is created based on the raw geolocator data

tag <- tag_create(id = "CB619")
## ✔ Read './data/raw-tag/CB619//CB619.deg'
## Warning: ! No file is matching '*.lux'.
## → This sensor will be ignored.

The raw data for this tag id should be stored in "./data/raw-tag/CB619/" following the default structure described in GeoPressureTemplate.

You can use the generic plot() function to visualize the tag data.

plot(tag, type = "pressure")

Depending on when you equipped the bird and when your tag started recording data, you will likely need to crop your data to specific dates. As it is bad practice to modify your raw data, we recommend using the crop_start and crop_end arguments in tag_create().

1.2 Label tag into stationary periods

Labelling tracks involves two steps:

  1. Label periods of flight, which, by extension will define the STAtionary Periods (called stap in the code), during which the bird is assumed to remain at the same location (+/- tens of kilometers) and same elevation level (+/- few meters)
  2. Discard pressure measurements which should not be used to estimate position (due to, for example, sensor error, flight, minor/short changes in elevation level, etc.)

1.2.1 Initialize and create the label .csv file

Use tag_label_write() to initiate the label (i.e., empty label) and create the label file to "./data/tag-label/CB619.csv".

## ℹ No label data.
## → Initialize automatically label using `tag_label_auto()`
## ✔ './data/tag-label/CB619.csv' written successfully.

1.2.2 Label manually on Trainset

Open https://trainset.raphaelnussbaumer.com/ and click on “Upload Tag Label” to load your .csv file. Instructions on how to label the file can be found in the dedicated chapter labelling tracks. Once you have finished, export the new csv file in the same folder /data/tag-label/CB619-labeled.csv (TRAINSET will automatically add -labeled in the name).

Print screen of the manual labelling of tag data in TRAINSET. See labelling tracks for more information.
Print screen of the manual labelling of tag data in TRAINSET. See labelling tracks for more information.

1.2.3 Read labelled file

Read the exported file with tag_label_read() to update tag$pressure (and, when relevant, tag$acceleration), with a new label column.

tag <- tag_label_read(tag)
kable(head(tag$pressure))
date value label
2021-07-01 02:30:10 954.2268
2021-07-01 03:00:10 954.0889
2021-07-01 03:30:10 953.8978
2021-07-01 04:00:10 953.6862
2021-07-01 04:30:10 953.4887
2021-07-01 05:00:10 953.0179

1.2.4 Compute stationary periods

tag_label_stap() then creates the stationary periods based on these labels:

tag <- tag_label_stap(tag, quiet = TRUE)
kable(head(tag$stap))
stap_id start end
1 2021-07-01 02:30:10 2021-09-24 00:00:10
2 2021-09-24 11:30:10 2021-09-24 23:30:10
3 2021-09-25 11:00:10 2021-09-25 23:30:10
4 2021-09-26 13:00:10 2021-09-27 04:00:10
5 2021-09-27 08:30:10 2022-04-06 00:30:10
6 2022-04-06 10:30:10 2022-04-07 00:00:10

Plotting the pressure timeseries of tag provides additional information:

plot(tag, type = "pressure", quiet = TRUE)

Once you have created the tag label file (i.e., CB619-labeled.csv), you can use tag_label() directly to read the label and compute stationary periods.